home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 41 / Amiga Format CD41 (1999-06)(Future Publishing)(GB)[!][issue 1999-07].iso / -seriously_amiga- / misc / mmulib / readme < prev    next >
Text File  |  1999-04-19  |  21KB  |  537 lines
  1. The mmu.library project © 1998,99 the mmu.library development group, THOR
  2. -----------------------------------------------------------------------------
  3.  
  4. Release 0.26
  5. ------------
  6.  
  7.     - Fixed a bug in the exception handling, forgot to restore a6.
  8.     - Fixed the return value of RebuildTree(). It's now TRUE on
  9.       success, not DOSTRUE.
  10.     - Fixed a bug in the table builder, merged sub-tree were released
  11.       incorrectly.
  12.     - Added the WithoutMMU() LVO entry.
  13.     - Removed the AllocLineMem() LVO, this one was useless.
  14.  
  15. Release 0.25
  16. ------------
  17.  
  18.     - Debugged 060 exception handler again. Found only one bug, ROM
  19.       emulation was broken.
  20.     - Enhanced AbsExecBase accesses - does no longer block interrupts
  21.       unnecessary.
  22.     - Fixed parts of the exception handler to read the faulty instruction
  23.       from the correct function code space.
  24.     - Added a complicated test for the EC030 processor that should
  25.       finally work.
  26.     - Enabled the MMULib internal exception handler test.
  27.     - Removed all accesses to the ppc.library and reserved entries.
  28.       PPC.lib compatibility is no longer an issue for me. The MMU.lib
  29.       is WarpOs-compatible, though, as long as the system isn't 
  30.       infected by Ralph's "software".
  31.     - Added a safety test in the MMUCacheTest program to avoid
  32.       hangs.
  33.  
  34. Release 0.24
  35. ------------
  36.  
  37.     - Fixed the 030/851 exception handler, especially the emulation
  38.       of instruction access of a possibly invalidated zero page,
  39.       now really, *BIG* thanks to Dave!
  40.     - MuForce does no longer ignore a remapped ROM. (Oops!)
  41.     - MuForce does no longer touch the mapping of the fspace
  42.       unless told to do so.
  43.     - Fixed the assembler includes and autodocs, thanks to Tilman!
  44.     - The context management of the library does no longer
  45.       reset the remap destination in case the memory remap flag
  46.       is not included in the mask settings. (Oops!)
  47.     - Fixed the MMU table builder for MMU tables using more than
  48.       32K entries.
  49.     - The startup code selects now a better page layout for 030/851
  50.       processors.
  51.     - MuForce tries now to re-use an already relocated vector base
  52.       if possible.
  53.     - Tiny speedup in the "InstallDescriptor" routine could speed up
  54.       MMU table building. There's room for more speedups, though.
  55.     - Added a "nommu" flag for the MMUCacheTest program to check    
  56.       your HD without the mmu.library. If this flag is used, the
  57.       program *MUST* be run without the mmu.library currently loaded.
  58.  
  59. Related fixes of COP (release 1.73, not included in this distribution):
  60.     - Fixed emulation of instruction access to the zero-page.
  61.     - Fixed the RestoreVBR option.
  62.     - Fixed the MMU disable mechanism on startup.
  63.  
  64. Special thanks goes to Dave "Ragman" for finding a lot of bugs in the 0.21
  65. release.
  66.  
  67. -----------------------------------------------------------------------------
  68.  
  69. Tests to be done for the 0.25:
  70.  
  71. - Please copy the "MMUCacheTest" program to your HD, then reset the
  72. computer, hold both buttons and disable the startup-sequence from the
  73. boot menu. (The MMUCacheTest program has been fixed, there's a chance that
  74. tests run better with the 0.25!)
  75.  
  76. On the boot shell, enter
  77.  
  78. "SetPatch"
  79.  
  80. to install the system specific patches, *DO NOT* start any other program.
  81. Please run now
  82.  
  83. MMUCacheTest DH0: nommu
  84.          ^^^
  85.     insert the name of your HD here, should be tried with other
  86.     devices as well.
  87.  
  88. Please let me know how this goes; especially, I'm interested in the last
  89. line of output from the program:
  90.  
  91. Task switching was disabled 0 times, run 122659 RAM accesses.
  92.             ^^^^^^^^
  93.     This number shouldn't differ from zero.
  94.  
  95. Second test would be to run just the same program again, but without
  96. the "nommu" keyword.    
  97.  
  98. Except that, as usual, just try the software: MuForce, MuFastRom and
  99. all the other stuff.
  100.  
  101. -----------------------------------------------------------------------------
  102.  
  103. Compatibility warnings and bad software:
  104.  
  105. - The MMU tables generated by the "CPU FastROM" command, an official CBM tool,
  106. are simply wrong if run on a 030 processor. Chip memory is marked as
  107. "cacheable", which is plain wrong. Already spoke to Michael Sinz who agrees
  108. in that point. Don't use it, run "MuFastRom" instead.
  109.  
  110. - The MMU tables build by "SetCPU FastRom" are not very well suited for 
  111. MuForce. The MMU library will replace the table layout by something more
  112. adapted.
  113.  
  114. Since these programs may install a "bogus" exception vector, you shouldn't
  115. run both programs with the "FastROM" option. If you absolutely want to do, 
  116. run them *before* installing any MMU.lib related program and COP - remember, 
  117. you have been warned. "MuFastROM" will do better once the library is finished.
  118.  
  119.  
  120. - CMQ060.lha from the Aminet: This program uses the MOVE16 instruction to
  121. "speed up" the copy mem routines of the Os. Besides that the speedup is
  122. minimal, you should be informed that this instruction is not fully 
  123. supported by the Amiga hardware. A MOVE16 into the chip memory could yield
  124. to "strange and wonderful things", and may or may not work. Its burst
  125. accesses simply don't fit into the DMA access mechanism of the Amiga 
  126. custom chips. (Note that no other instruction will try burst accesses
  127. into non-cacheable memory!)
  128. Moreover, if a MOVE16 crashes, the mmu.library is out of buisiness, it will 
  129. simply guru. Do not run this program!
  130.  
  131. MOVE16 is one of the non-supported instructions in an Amiga system, others
  132. are TAS, CAS and CAS2 (which are of little use in a single processor system).
  133.  
  134. For more detailed information of MOVE16, check either the enforcer.guide or
  135. the motorola documentation, I'm not making this up, and this is not 
  136. mmu.library related.
  137.  
  138. Known Bugs:
  139. -----------
  140.  
  141.     The MMU table manager rebuilds currently the MMU tables for a
  142.     complete memory block even if only a minor sub-block was changed.
  143.     Therefore, it may take longer to build the MMU table than absolutely
  144.     required. I decided not to change this behaiviour because it
  145.     keeps the mmu tables clean and optimized and avoids fragmentation.
  146.  
  147.     The MMU library builds currently 68030 MMU tables with the
  148.     REPAIRABLE flag set less efficient than it could. However, it 
  149.     was felt that a consistent table layout is more helpful than the
  150.     (minimal) speedup.
  151.  
  152.     The library does not yet provide a mechanism to adjust the page
  153.     size, even though it is flexible enough to adapt to any page size
  154.     possible. This feature will be added in the form of tags to the
  155.     CreateContext() call.
  156.  
  157.     The library does not yet contain a workaround for a 040 firmware
  158.     bug: If an illegal, line A, chk or unimplemented floating point
  159.     instruction is located at the last 16 bits of a page and the next
  160.     page is not available, the 040 generates an access fault instead
  161.     of the proper exception. The fault address is the address of the
  162.     missing page, and the PC points to the instruction in the preceeding
  163.     page. This doesn't matter too much currently, it might become
  164.     relevant in a VM system.
  165.  
  166.     Somehow the library seems to cause hangs of DMA/PIO devices. I
  167.     can't comment on that currently since I haven't had a chance to
  168.     test that myself. I can't comment on that, I've no idea...
  169.  
  170.     Might happen that the library causes somehow hangups of my 040
  171.     system. Possibly because of a 040 MMU firmware bug, possibly 
  172.     because of interactions with my debugger COP, possibly because
  173.     I'm using an old release of the 68040.library. This has to be
  174.     checked out, still - haven't had a hang for weeks now....
  175.  
  176.  
  177. These bugs will be fixed within the next releases of the library, including
  178. all the other bugs you may find.
  179.     
  180. -----------------------------------------------------------------------------
  181.  
  182. Special thanks goes to:
  183.  
  184. -Ralph Babel for giving information about the CachePreDMA/CachePostDMA
  185.  functions and for some internals allowing me to write the MuOmniSCSIPatch.
  186. -Carsten Schlote for starting development of a mmu.library aware 68060.lib.
  187. -Michael Sinz (a real BIG thank you!) for discussing a lot of details of
  188.  CachePreDMA/CachePostDMA, for sending me the sources of these functions
  189.  in his 68040, and especially - and that's really great - for making the
  190.  Enforcer sources available and for allowing me to reuse the exception
  191.  handler of the Enforcer. This will happen in one of the next releases.
  192. -Bjoern Schmidt for allowing me to run some tests on his 060 and for
  193.  keeping several afternoons free for me.
  194. -All the testers for running tests and sending me detailed information about
  195.  their systems.
  196.  
  197. Thank you to all of you, this project won't clearly possible without your
  198. support!    
  199.  
  200. -----------------------------------------------------------------------------
  201.  
  202. What is this:
  203. -------------
  204.     The mmu.library provides functions for MMU related operations
  205.     as write- or read-protecting certain areas of memory for a
  206.     given set of tasks, or marking memory regions as "swapped"
  207.     virtual memory support. It offers an abstraction level on top
  208.     of the actual MMU and a unified interface for MMU purposes.
  209.  
  210.     The MMU lib does NOT implement virtual memory, that's the purpose
  211.     of another library - the memory.library. There's no much reason why
  212.     any application except the memory.library and probably some debugging
  213.     tools should call this library directly. The memory.library functions
  214.     on top of this library should suffer for "all day purposes".
  215.  
  216.     The goal of the mmu.library is to provide an "abstraction layer" on
  217.     top of the hardware, to allow programs to make use of the memory
  218.     management hardware of the more advanced members of the MC68K
  219.     processor family. Programs using the functions of the mmu.library
  220.     do not need to modify the MMU tables directly and hence will not
  221.     conflict with each other. The mmu.library interface provides all
  222.     necessary functions to do that. This will allow programs like
  223.     Enforcer and VMM to cooperate nicely with each other, provided both
  224.     use this library.
  225.  
  226. Since writing the mmu.library is a tough job, I need your help!
  227.  
  228. Currently, only two systems are available right here, a MC68030 40Mhz
  229. ad a MC68040 33Mhz. While this is better than before, I still need your
  230. help since the library is supposed to support all members of the MC68K
  231. family (the 68851, 68040 and 68060 MMUs). 
  232. Since I don't have all these systems available, I need your
  233. help - writing system software without being able to debug is "a bit" 
  234. tricky.
  235.  
  236.  
  237. What can I do as a non-developer:
  238. ---------------------------------
  239.  
  240. Testing! Check the documentation of the programs within the documentation,
  241. especially what you find the "MuTools" drawer, and lemme know how it goes.
  242.  
  243. Please run the MMUCacheTest program, too. It takes one argument, the
  244. name of a hard disk. Don't worry, it won't harm your HD, it will simply
  245. read sectors from it to test some critical MMU.library functions.
  246.  
  247. Please perform this test with as many "disk-like" devices as you can, i.e.
  248. hard disks, CD Roms, SCSI and IDE devices of various kinds.
  249.  
  250. Here's an example run:
  251.  
  252. 1.SYS:> MMUCacheTest DH0: <RETURN>
  253.  
  254. MMUCacheTest 0.20 (6.2.99) © THOR.
  255. Internal use only, no commercial use.
  256. Initial read, calculate checksum.
  257.  
  258. Running the initial device test.
  259. This test checks whether the connected device works reliable.
  260. It does NOT check the MMU code which is not needed for this
  261. initial run.
  262. This test SHOULD NOT fail. In case it does, your device or
  263. host adapter is broken, but not the MMU logic.
  264.  
  265. The initial test passed.
  266.  
  267. Running the real test. If this test fails, something is wrong
  268. with the CachePreDMA/CachePostDMA logic. In this case, please
  269. sent me an EMail so I can fix it.
  270. The MMU cache test passed. Run 165329 RAM accesses.
  271.  
  272.  
  273. In case any of the tests fail, or you see crashes, please let me know.
  274. THIS IS AN IMPORTANT TEST. If anything fails here, the future mmu.library
  275. might trash disk input.
  276.  
  277. If the tests pass, check the number of RAM accesses shown in the last line
  278. of the output. This number *should* be larger than zero. If it's not, then
  279. the test did effectively nothing. Please let me know in this case either,
  280. I'll try to invent a more effective test in this case.
  281.  
  282.  
  283. A third - non-MMU related - test is the SCSIDMATest program, please run
  284. this test as well.
  285.  
  286. It works like this:
  287.  
  288. 1) Run the SCSIDMATest program. It will print a message and wait for ^C.
  289. DO NOT YET abort the program.
  290.  
  291. 2) Play with your harddisk, read files, write files, whatever you like.
  292.  
  293. 3) Stop the program and please collect the output, and please send it to my
  294. email address at thor@math.tu-berlin.de.
  295.  
  296. Here's the output for my system:
  297.  
  298. CachePreDMA/PostDMA patches installed. Please start massive
  299. disk activity now, keep the program running for several minutes.
  300. Then remove it with ^C.
  301.  
  302. The patches have been removed.
  303. The DMA activity counter is 0. CachePreDMA called 0 times,
  304. 0 times without DMA_Continue, CachePostDMA called 0 times.
  305.  
  306. The DMA activity counter is of special interest. It should be zero, or at
  307. least a *small* number. If it's not, please lemme know the name of the
  308. device your HD is controlled by, i.e. "gvpscsi.device", "oktagon.device",
  309. "scsi.device", "cybscsi.device" etc... Would be nice if you could provide a
  310. version information as well, i.e. enter a line like
  311.  
  312. version gvpscsi.device
  313.  
  314. on the shell and lemme know about the output.
  315.  
  316.  
  317. What can I do as developer:
  318. ---------------------------
  319.  
  320. I'm still willing to give away the sources of the library, provided that
  321.  
  322. a) you keep them private and don't give them away (really!)
  323. b) you help me debugging the library by using them.
  324.  
  325. They are no longer included in the "standard" distribution because that
  326. would enlarge the archive unnecessary for most testers. In case you're
  327. interested, just sent me a note.
  328.  
  329. What about joining the mmu.library development group? This is just a couple
  330. of people contributing to this library by writing code and exchanging their
  331. wisdom by EMail. It's a non-profit organization that works on the development
  332. of this library. If, whenever, this library becomes a commercial product, 
  333. you'll get paid, of course. However, the current library, as it is, is planned
  334. to be freeware, so don't expect money. It doesn't look like there's currently
  335. a market for this library project, unfortunately. 
  336.  
  337. Contact me at thor@math.tu-berlin.de if you want to join this group.
  338.  
  339.  
  340. What can be done just now is to run this library on your machine and find
  341. and correct bugs. As I said, I haven't tested the 68851 and the 68060
  342. parts at all. 
  343.  
  344. You might also want to develop software for the library. You find the
  345. required includes and autodocs within this archive, as well as example
  346. sources. In case you need support, just contact me.
  347.  
  348. There are a lot of library functions that require a bit more testing:
  349.  
  350. - All the functions that bypass the abstraction layer:
  351.  
  352.     GetPageProperties(),SetPageProperties(),PhysicalPageLocation()
  353.  
  354. - Remapping of memory and adding this memory to the exec memory pool.
  355. - Building private contexts and swaps of the MMU tables on task swaps.
  356. - SWITCH and LAUNCH type exception handlers.
  357.  
  358. I haven't been able yet to run all required tests, sorry. 
  359.  
  360.  
  361. What is in this distribution:
  362. -----------------------------
  363.  
  364. Autodocs:
  365.     The preliminary version of the autodocs of the mmu.library and
  366.     the memory library, as well as a file describing some planned
  367.     implementation details.
  368.  
  369. Include:
  370.     The includes for a C compiler as well as the ".fd" file for the
  371.     library functions written so far. 
  372.  
  373. C_Sources:
  374.     C sources of sample programs. All programs that are distributed
  375.     under the THOR-Software licence are published here. The
  376.     sources of MuForce *are not* available because they are partially
  377.     copyrighted by Michael Sinz.
  378.  
  379. MuTools:
  380.     Contains a small collection of programs that make use of the MMU.
  381.     For details, check their guides in this drawer.
  382.  
  383. Shell_Only:
  384.     A couple of programs that can be run from the shell only, as there
  385.     are:
  386.  
  387.     MMUCacheTest:
  388.         Reads from HD, partially non-cache aligned to check whether
  389.         boundary pages of the DMA buffer are correctly marked as non-
  390.         cacheable. See above for how the test looks like.
  391.  
  392.     SCSIDMATest:
  393.         Checks whether the hard disk driver uses CachePreDMA/CachePostDMA
  394.         consistently. See above for the test. The source is included.
  395.  
  396.     TestMMU:
  397.         This program is purely for debugging purposes. If you run it,
  398.         you won't see any specific action. It simply opens the library
  399.         manually and executes the library init function in the task
  400.         context of the calling program. Hence, this program can be used
  401.         to step thru the lib-init function with a standard debugger
  402.         without the need to catch "ramlib".
  403.         If you still discover bugs and want to try, then load this
  404.         program into a debugger of your choice, and step thru it.                library.
  405.     
  406. Known bugs and problems of this implementation:
  407. -----------------------------------------------
  408.  
  409. Things that require testing:
  410.  
  411.     - TTx register parsing updated. Should work fine with all the
  412.       printouts I've collected, but you may still want to test it.
  413.     - 68851, and 68060 code likely untested, but I'm getting better. 
  414.       I NEED YOUR HELP!
  415.     - GetPageProperties/SetPageProperties.
  416.     - Adding remapped memory to the exec free list.
  417.  
  418. Things not yet implemented:
  419.  
  420.     - Patches for ppc libraries due to missing support. Grrr.
  421.     - Functions to setup a different page size.
  422.  
  423. Things the current design does not allow:
  424.  
  425.     - The MAPP_USED and MAPP_MODIFIED flags are not kept consistent
  426.       by the library except for MAPP_SINGLE pages. I consider this
  427.       as a minor problem since single page mode is required for
  428.       virtual memory anyways.
  429.     - MMU tables using the function codes. The amiga design shouldn't
  430.       allow this anyways, but I don't know whether there's a board
  431.       that makes use of them. (Doesn't look like, though).
  432.     - Boards with two different MMU's on board. I've heard some
  433.       rumours that there are actually 68040 boards with an additional
  434.       68851. The current library assumes a 68040 MMU.
  435.     - The current implementation does not yet check completely whether
  436.       an "EC" type processor (without an MMU) is on-board. This check
  437.       should work for the 68060 since there's a hardware register for
  438.       it, and there's now even a test for a EC040 which hopefully
  439.       works, but there's NO test for the EC030 because I wasn't able
  440.       to find a simple one. The library contains currently a 
  441.       complicated one which is still "commented out" because it
  442.       requires the full exception handler which hasn't been tested
  443.       too much.
  444.     - The current design allows only one global supervisor table since
  445.       I thought a task specific supervisor table might not make too
  446.       much sense anyways. 
  447.  
  448. I would really enjoy if someone (Ralph Schmidt?) could give me some internal
  449. information about the P5 boards and their MMU usage. I'm now well informed
  450. about the internals of the "real" 68040 and 68060 libraries (and not of the
  451. P5 wierdos of this library), great thanks to Ralph Babel and Michael Sinz.
  452.  
  453. However, I'm still looking for information about the ppc.library. I got the
  454. autodocs, but this is unfortunately not sufficient. The following questions
  455. remain:
  456.  
  457. - Does the ppc.library route all MMU table accesses thru PPCAllocMem(),
  458.   or do I have to patch all entries?
  459. - Is there an entry in the P5 68060 library to change the MMU table?
  460. - Is it enough to adapt the cache modes of the PPC allocated memory manually,
  461.   or does the ppc.library more dirty tricks?
  462.  
  463. Any kind of information will be appreciated!
  464.  
  465.  
  466. Debugging:
  467. ----------
  468.  
  469. Yes, that's a problem of its own. Obviously, the MMU library uses some
  470. "heavy magic" supervisor code which is not available for a standard monitor.
  471. Even though the DevPac "MonAm" is a nice and powerful debugger, it's not
  472. powerful enough for these tricks. There's currently - up to my knowledge -
  473. only one debugger that can do this for you, and that's my own... (-;
  474.  
  475. Check the Aminet and my web-page for COP, then read the documentation. If,
  476. after reading, you STILL want to use it, you're the right guy for this
  477. job... (-;
  478. COP might be setup to load the symbols of the library, to help you a bit.
  479.  
  480. The current version of COP is 1.73. Try to get the latest, if possible.
  481.  
  482. Recommended reading:
  483. --------------------
  484.  
  485. The following books are recommended reading:
  486.  
  487.  
  488. Motorola 68030 Enhanced 32-bit Microprocessor User's Manual    
  489.     MC68030UM/AD Rev.3
  490.  
  491. Motorola 68040 User's Manual                    
  492.     M68040UM/AD Rev.1
  493.  
  494. Motorola 68060 User's Manual                    
  495.     M68060UM/AD Rev.1
  496.  
  497. Motorola M68000 Family Programmer's Reference Manual        
  498.     M68000PM/AD Rev.1
  499.  
  500. Amiga Hardware Reference Manual, 3rd ed.
  501.     Addison-Wesley Publishing Company, Inc.
  502.     ISBN 0-201-56776-8
  503.  
  504. Amiga ROM Kernal Reference Manual, 3rd ed., Volume "Libraries"
  505.     Addison-Wesley Publising Company, Inc.
  506.     ISBN 0-201-56774-1
  507.  
  508. The Amiga Guru Book, 2nd Ed.
  509.     Ralph Babel, Taunusstein 1989,1993
  510.  
  511. Additional sources:
  512.     The Amiga Developer CD V1.1 
  513.     (newer versions are already available, but 1.1 is good enough).
  514.  
  515.     The Enforcer.guide.
  516.  
  517.     Michael Sinz's documentation in the AmigaMail, on the DevCD 1.1.
  518.  
  519. Final words:
  520. ------------
  521.  
  522. The mmu.library and the memory library will be my last project for the Amiga. 
  523. It depends a bit on what happens with the Amiga in the next two years whether 
  524. a PPC version of this library is required or not; hence, after all, this
  525. can't be much more than a toy project that came several years too late.
  526.  
  527. However, as it looks now, Amiga goes PC. I'm currently not willing to 
  528. support this step and the Intel/Microsoft illnesses.
  529.  
  530. \begin{sarcastic}
  531. While Commodore just dug the grave for the Amiga, Gateway is turning it into
  532. a zombie.
  533. \end{sarcastic}
  534.  
  535. So long,
  536.     Thomas
  537.